home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / winstall.lzh / WINSTALL.DOC < prev    next >
Text File  |  1993-10-05  |  16KB  |  442 lines
  1.                             Winstall
  2.                           User's Guide
  3.                             Version 1
  4.  
  5. Introduction
  6. ============
  7.  
  8. Winstall automatically installs software packages by copying files 
  9. from one or more source diskettes onto your customer's system.
  10. Winstall simplifies the installation process and reduces the chance
  11. that your customer will incorrectly install your software package.
  12.  
  13.  
  14. Features
  15. ========
  16.  
  17.   * Supports installation to hard disk or floppy diskette
  18.   * Maximizes use of memory during installation to reduce floppy 
  19.     swapping
  20.   * Supports multiple source disk installations, and prompts the user 
  21.     to insert disks as needed
  22.   * Automatically creates directories as needed on the destination disk
  23.   * Can patch the installation drive and directory into a file
  24.   * Can copy up to 256 files per package
  25.   * Can install multiple packages from a single source disk (or set 
  26.     of disks)
  27.   * Checks for required available disk space before beginning 
  28.     installation
  29.   * Can check that the user has inserted the correct disk in a 
  30.     multi-disk set
  31.   * Prompts the user for confirmation before overwriting files
  32.   * Displays "percentage complete" progress bar during installation
  33.  
  34.  
  35. Terms Used
  36. ==========
  37.  
  38. The following terms are used throughout this User's Guide.
  39.  
  40. Customer: The person who installs your package onto their system.
  41.  
  42. Destination drive: The disk drive, selected by the customer, where 
  43. the package will be copied during installation.
  44.  
  45. Directory: Folder.
  46.  
  47. Installation path: The drive and path, selected by the customer, 
  48. where the package will be copied during installation.
  49.  
  50. Package: The set of files (programs and data files) forming a single 
  51. software product.
  52.  
  53. Path: A chain of zero or more directories, possibly ending in a file
  54. name, which defines the location of a file or directory within a
  55. directory tree.
  56.  
  57. Source disk: A disk containing the package to be installed.
  58.  
  59. A term enclosed in angle brackets (e.g., <disk id>) is used as a 
  60. place holder for another term (usually described in the surrounding
  61. text). The angle brackets are not part of the term.
  62.  
  63.  
  64. General Operation
  65. =================
  66.  
  67. To use Winstall, you create a set of one or more source disks 
  68. containing your package. Next, you create an installation script file
  69. and copy it, along with WINSTALL.PRG, onto your source disk.
  70.  
  71. You distribute your source disk(s) to your customer. The customer 
  72. runs WINSTALL.PRG, which reads the installation script and performs
  73. the installation.
  74.  
  75.  
  76. Creating the Installation Script
  77. ================================
  78.  
  79. The installation script tells Winstall how to perform the 
  80. installation. Installation script files have an "INS" extension. When
  81. it runs, Winstall looks for a file called WINSTALL.INS. If it finds
  82. the file, Winstall carries out the instructions it contains. If it 
  83. cannot find WINSTALL.INS, Winstall presents a file-selection form and
  84. lets the customer select an INS file. This is described more fully in
  85. the "Multi-package Installation" section.  You can create the INS file
  86. with an ASCII text editor. The file contains a series of lines. Each
  87. line represents a single command. The character in the first column 
  88. of each line is the command code. If the command takes parameters,
  89. then exactly one space must separate the command code from the first
  90. parameter -- i.e., the first parameter starts in column 3.
  91.  
  92. A sample INS file is shown below.
  93.  
  94.   # Installation script for Turbo Blaster
  95.   n Turbo Blaster
  96.   v 2.34
  97.   d TBLASTER
  98.   s 1343254
  99.   f 1:\tblaster.prg %d\tblaster.prg
  100.   f 1:\tax.jj %d\samples\tax.tb
  101.   f 1:\tblaster.acc %b\tblaster.acc
  102.   f 2:\templt1.tem %d\template\templt1.tem
  103.   f 2:\templt2.tem %d\template\templt2.tem
  104.   f 2:\tblaster.lib \lib\tblaster.lib
  105.   a [1][Please see README.TXT  |for release notes.  ][OK]
  106.   b [1][Don't forget to fill in |your registration card. ][OK]
  107.  
  108. Following is a description of the Winstall commands.
  109.  
  110. #: Comment
  111.  
  112.   Defines a comment line. The remaining text on the line is ignored 
  113.   by Winstall. There is no limit on the number of comment lines.  
  114.   Comment lines are optional.
  115.  
  116.   Example:
  117.  
  118.   # Installation script for Turbo Blaster
  119.  
  120. a: After Message
  121.  
  122.   Defines the text for an alert that will appear at the end of (after) 
  123.   a successful installation. The parameter is a string suitable for the
  124.   second parameter of form_alert():
  125.  
  126.   * The first component, a number enclosed in square brackets, 
  127.     determines the type of icon displayed in the alert: [1]: Exclamation;
  128.     [2]: Question; [3]: Stop.
  129.  
  130.   * The second component is a sequence of text lines surrounded by 
  131.     square brackets. Each line is separated by a "|" character. Up to five
  132.     lines may be defined. Each line may contain up to 32 characters. The
  133.     alert looks best if all lines are approximately the same length --
  134.     uses spaces to pad them.
  135.  
  136.   * The third component is a button label surrounded by square 
  137.     brackets.  Only one "a" command may be defined per installation. The
  138.     "a" command is optional. If it is omitted, no message will be
  139.     displayed.
  140.  
  141.   Example:
  142.  
  143.   a [1][Please see README.TXT  |for release notes.  ][OK]
  144.  
  145. b: Before Message
  146.  
  147.   Defines the text for an alert which will appear before installation 
  148.   begins. See the description of the "a" command for details.
  149.  
  150.   Example:
  151.  
  152.   b [1][Don't forget to fill in |your registration card. ][OK]
  153.  
  154. c: Check Disk Ids
  155.  
  156.   Tells Winstall to check the id of each source disk after a disk swap. 
  157.   This feature is useful in multiple source-disk installations, where
  158.   the customer is asked to swap disks several times. If this feature is
  159.   enabled, Winstall will check for the existence of a special disk id
  160.   file on the source disk to ensure that the customer inserted the 
  161.   correct one. The special disk id file is named <disk id>.! (for 
  162.   example, 1.! or INSTALL.!). See the description of the "f" command for
  163.   more information on disk ids. Only one "c" command may be defined.  
  164.   The "c" command is optional. If it is omitted, Winstall will not check
  165.   disk ids. The "c" command takes no parameters.
  166.  
  167. d: Default Destination Directory
  168.  
  169.   Defines the name of the default directory where you package will be 
  170.   installed. During installation, Winstall determines the default
  171.   destination drive (A: unless the customer has a hard drive, in which
  172.   case it is C:) and constructs the default installation path from the
  173.   drive and directory. For example, if you define the default directory
  174.   as TBLASTER and Winstall determines that the customer has a hard
  175.   drive, Winstall will use C:\TBLASTER as the default installation 
  176.   path. Winstall allows the customer to edit the default installation
  177.   path during installation. Only one "d" command may be defined. The "d"
  178.   command is mandatory.
  179.  
  180.   Example:
  181.  
  182.   d TBLASTER
  183.  
  184. f: Copy file
  185.  
  186.   Defines the name of a file that must be copied from a source disk to 
  187.   the destination path during installation. The "f" command uses the
  188.   following syntax:
  189.  
  190.   f <source file> <destination file>
  191.  
  192.   The <source file> component uses the following syntax:
  193.  
  194.   <disk id>:<path>
  195.  
  196.   <disk id> is a string (maximum 8 characters; no spaces allowed) 
  197.   defining the source disk containing the file to copy. During
  198.   installation, Winstall may prompt the customer to insert this disk in
  199.   the source drive with a message like this:
  200.  
  201.   Please insert <package name> disk "<disk id>" in drive A:.
  202.  
  203.   Leave the disk id blank if your package is distributed on one source 
  204.   disk.
  205.  
  206.   <path> is the path -- directories and file name -- of the source
  207.   file. Winstall uses this path to locate the source file on the source
  208.   disk.
  209.  
  210.   The <destination file> component uses one of the following formats:
  211.  
  212.   %d\<path>
  213.   %b\<path>
  214.   \<path>
  215.  
  216.   %d is a special token that is replaced with the installation path 
  217.   selected by the customer during installation. Use this form of the
  218.   <destination file> parameter to copy the file to the installation 
  219.   path.
  220.  
  221.   %b is a special token that is replaced with